#!/usr/bin/env python
# -*- coding: utf-8 -*-

from abc import ABC, abstractmethod
from typing import Dict, List, Any, Optional

class VectorStoreInterface(ABC):
    """
    向量存储接口，定义向量数据库必须实现的方法
    """

    @abstractmethod
    def store_node_vector(self, vid: str, node_type: str, node_text: str, vector: List[float], metadata: Dict[str, Any] = None) -> bool:
        """
        存储节点向量

        Args:
            vid: 节点ID
            node_type: 节点类型 ('class', 'function' 或 'annotation')
            node_text: 节点文本内容
            vector: 节点的嵌入向量
            metadata: 节点元数据

        Returns:
            操作是否成功
        """
        pass

    @abstractmethod
    def get_node_vector(self, vid: str) -> Optional[Dict[str, Any]]:
        """
        获取节点向量

        Args:
            vid: 节点ID

        Returns:
            节点数据字典或None
        """
        pass

    @abstractmethod
    def get_node_by_original_id(self, original_id: str) -> Optional[Dict[str, Any]]:
        """
        通过原始ID获取节点向量

        Args:
            original_id: 原始节点ID

        Returns:
            节点数据字典或None
        """
        pass

    @abstractmethod
    def search_similar_vectors(self, query_vector: List[float], node_type: Optional[str] = None, top_k: int = 10) -> List[Dict[str, Any]]:
        """
        搜索与查询向量最相似的节点

        Args:
            query_vector: 查询向量
            node_type: 节点类型过滤 ('class', 'function' 或 'annotation')
            top_k: 返回结果数量

        Returns:
            相似节点列表，按相似度降序排序
        """
        pass

    @abstractmethod
    def delete_node_vector(self, vid: str) -> bool:
        """
        删除节点向量

        Args:
            vid: 节点ID

        Returns:
            操作是否成功
        """
        pass

    @abstractmethod
    def get_stats(self) -> Dict[str, Any]:
        """
        获取向量存储统计信息

        Returns:
            统计信息字典
        """
        pass

    @abstractmethod
    def close(self) -> None:
        """关闭资源"""
        pass